<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger: Getting Started</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1>Debugger: Getting Started</H1>

    <P>The debugger supports debugging native user-mode applications for Linux, macOS, and Windows
    on 64-bit x86 and often arm64, e.g., when on "Apple Silicon." While not official, it also
    supports a variety of other platforms, so long as Ghidra can connect to a debugger that
    supports it. Launching is accomplished by connecting to the respective debugger for the target
    platform: GDB on Linux, LLDB on macOS, and the Windows Debugger (<TT>dbgeng.dll</TT>) on
    Windows. Several launch configurations are already included, and new launchers are fairly
    easily added by writing shell scripts.</P>

    <H2>Pay Attention to Errors</H2>

    <P>Many actions are taken automatically on behalf of the user, e.g., reading registers when a
    target is paused. In most cases, errors on automatic actions are dropped to the <A href=
    "help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A>, as displaying
    them in a dialog could become a pest. That said, if things still don't seem right, please check
    the terminal or Ghidra's application log.</P>

    <H2><A name="launching">Launching a Target</A></H2>

    <P>Starting up the Ghidra Debugger for user-mode debugging of a local process usually entails
    just two steps:</P>

    <OL>
      <LI>Open (or import) your program into the Debugger tool</LI>

      <LI>Click the <B>Launch</B> <IMG alt="(bug icon)" src="icon.debugger"> button in the main
      toolbar</LI>
    </OL>

    <P>The first time you launch a given program, you may be asked to select and configure a
    specific launcher. To load the default Debugger tool, from the main Ghidra application window
    select <B>Tools &rarr; Import Default Tools...</B> from the menus. Select
    "defaultTools/Debugger.tool", and hit <B>OK</B>. The Debugger tool will be added to the Tool
    Chest.</P>

    <P>To launch the tool, you have several options, identical to those you might use to launch the
    CodeBrowser tool. You can click the Debugger icon to launch an empty Debugger tool. You can
    drag a program that you have already imported from the Active Project window onto the tool icon
    in the Tool Chest, or you can right-click on one of the programs in the project and pick
    <B>Open With &rarr; Debugger</B>. If you open an empty Debugger tool, you can add programs to
    it later in the usual ways, e.g. via <B>File &rarr; Import File...</B> or by
    dragging-and-dropping programs onto the running tool.</P>

    <P>The default tool is pre-configured with a collection of plugins relevant to both dynamic and
    static analysis. As always, there is some chance that the tool will launch with some portion of
    the plugins not displayed or with a less-than-optimal layout. To verify which plugins you have,
    you can select <B>File &rarr; Configure</B>. "Debugger" should already be selected. Choosing
    <B>Configure All Plugins</B> <IMG alt="(the plug icon)" src="icon.extension.configure"> near
    the top right should show the full list of pre-selected plugins. Debugger-related plugins all
    begin with "Debugger" or "TraceRmi."</P>

    <P>For the <B>Launch</B> button to work, you must (a) have the program you wish to run visible
    and selected in the static Listing window, and (b) have imported the program from the place it
    lives on the local system. In other words, the file path associated with the program should be
    the path to the executable for the current file system. You can verify this using the <B>Help
    &rarr; About my_program</B> menu item in the main tool bar. For example, on a Linux system, if
    you've imported "xclock", <B>Help &rarr; About xclock...</B> should have an entry at the bottom
    of the page for "<TT>Executable Location: /usr/bin/xclock</TT>".</P>

    <P>When you launch the target by this method, a number of changes should be evident in the GUI.
    A Terminal should appear, containing the actual back end debugger, likely including some
    initialization messages and diagnostics. A new trace will appears in the <A href=
    "help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A>. A new tree
    structure will be populated within the <A href=
    "help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window. The remaining
    windows will be populated with current trace information. Please be patient, on some platforms
    it may still take some time for things to populate and settle. The <A href=
    "help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A> should provide
    some hints as to ongoing activity.</P>

    <H2>Debugger Components</H2>

    <P>Some of the more commonly accessed components are explained below. They also have their own
    help pages.</P>

    <H3>Terminal</H3>

    <P>The terminal window allows a user command-line access to the native debugger. For Linux,
    this means the standard GDB command line interface; for macOS, the LLDB command line interface;
    and for Windows, the WinDbg/kd command set. While basic tasks may not require using the command
    line interface, more complicated debugging scenarios invariably require commands specific to
    the target which have not or cannot be implemented generically in the GUI. Additionally, if for
    some reason the connection to Ghidra fails, the terminal will still provide command-line access
    for diagnostics and/or manual recovery.</P>

    <H3>Model</H3>

    <P>The <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window
    displays a directory of objects in a 3d-party debugging session using a structure determined by
    its back-end plugin. In some cases, e.g., when the back end does not recognize the target's
    architecture, other displays may struggle to display meaningful information. Even then, this
    window should provide a good overview of the debugger's and its target's current state. It may
    also provide some useful commands for diagnostics, but the terminal may be a better choice.</P>

    <H3>Listing</H3>

    <P>The back end uses its connection to Ghidra to create a trace and record target information
    into it. The Debugger's various windows all derive their contents from the current trace.
    Perhaps the most important of these is the <A href=
    "help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A> window. Analogous to
    the static listing, it displays the raw bytes in the target's memory and allows the user to
    mark them up, e.g., disassemble, place data types, comment. Unlike the static listing, this
    window shows live bytes in all valid memory, including stacks and heaps. When it can, the
    Ghidra debugger keeps the cursor locations in the Static and Dynamic Listings synchronized.</P>

    <H3>Controls and Miscellany</H3>

    <P>The main toolbar provides your standard debugging controls, e.g., resume, step, interrupt.
    They apply to the current thread or frame as defined by the back end's command set. For
    details, see the <A href=
    "help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control</A> plugin. During or
    after a session, the user can examine trace history or emulate by changing control mode.</P>

    <P>Breakpoints can be set from either the <A href=
    "help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html">Breakpoints</A> window
    or the <A href=
    "help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Listing</A>.
    The <A href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A>
    and <A href="help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html">Stack</A> windows
    reflect the state of the current thread, which can be selected in the <A href=
    "help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html">Threads</A> window. Typically,
    the thread selected for the trace in the Threads window is kept in sync with the
    active/selected/focused thread in the back-end debugger, but not always.</P>

    <H3>Console</H3>

    <P>The <A href="help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A>
    is a central place for reporting activity, errors, and suggesting actions. This and the
    Terminal are the first places to look when troubleshooting.</P>
  </BODY>
</HTML>
